home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / prog_disc / volume_8 / issue_06 / risc_os / kernel / NewSWIs < prev    next >
Encoding:
Text File  |  1988-05-20  |  8.9 KB  |  263 lines
  1. > Sam.A2Docn.NewSWIs
  2.  
  3. SWI OS_ChangeEnvironment (&40)
  4. ==============================
  5.  
  6. This has been extended since 1.20; there are two new reason codes.
  7.  
  8. Application space size can be set with reason code 14. This is used
  9. in conjunction with the memory remapping facilities.
  10.  
  11. The Currently Active Object pointer can be set with reason code 15. This
  12. is the pointer checked by the MOS before it kills modules, or moves
  13. application space.
  14.  
  15.  
  16. SWI OS_SubstituteArgs (&43)
  17. ===========================
  18.  
  19. This has been extended in Arthur 2: setting the top bit of r0 on entry
  20. stops it appending any unused parameters on the end of the output line.
  21.  
  22. SWI OS_PrettyPrint (&44)
  23. ========================
  24.  
  25. This has been extended in Arthur 2 to cope with compacted text. If character
  26. 27 appears in the text to be printed, it indicates that a "dictionary" entry
  27. should be substituted instead, and which entry is indicated by the next byte.
  28. 1-255 means the nth entry in the passed dictionary.
  29. 0 is special: it means substitute the string pointed at by r2 on entry.
  30.  
  31. The format of a dictionary is a linear list of entries; each entry is a length
  32. byte followed by a null-terminated string. Note that this means that a
  33. dictionary does not have to have 255 entries; it can be terminated by a
  34. zero-length entry.
  35.  
  36. In: r0 -> string to print
  37.     r1 -> dictionary (0 means use the MOS internal dictionary)
  38.     r2 -> special string
  39.  
  40. To see the MOS internal dictionary, use the following program:
  41.  
  42. DIM buffer 3
  43. buffer?0 = 27
  44. buffer?2 = 0
  45. FOR I%=0 TO 255
  46.   buffer?1=I%
  47.   PRINT"Dictionary entry ";I%
  48.   SYS "OS_PrettyPrint",buffer,0,"<special string>"+CHR$0
  49.   PRINT
  50. NEXT
  51.  
  52.  
  53. SWI OS_ReadArgs (&49)
  54. =====================
  55.  
  56. Inputs: R0 pointer to key definition
  57.         R1 pointer to input string
  58.         R2 pointer to output vector
  59.         R3 size of output vector
  60.  
  61. Output: R0-R2 preserved
  62.         R3 bytes left in vector
  63.  
  64. The key definition string is pretty obvious if you've used RdArgs or
  65. DecodeArgs (et al): keywords are alphanumerics or "_", with aliases separated
  66. by "=", and qualifiers coming after "/". "," separates arguments.
  67.  
  68. Qualifiers: /A means keyword must always be given a value
  69.             /K means keyword must always precede its value
  70.             /S means the option is a switch; presence only is reported
  71.             /E means the Expression Evaluation SWI should be called to
  72.                transform the given value
  73.             /G means GSTRans should be called to transform the given value
  74.  
  75. Some of these options are of course in conflict: meaning of /S/G  etc. is
  76. undefined.
  77.  
  78. Input string: keywords are marked by "-", but "-" does not force the next
  79. item to be a keyword; this would cause problems with /E arguments (see
  80. below). Keywords can be be given single letter abbreviations.
  81. Switch keywords, when given as single letters, can also be elided.
  82.  
  83. Results: if there are n arguments in the R0 string, then R2 starts with
  84. n words, one for each argument. 0 in the word indicates that the
  85. argument was missing; for switches, non-zero therefore means the switch
  86. was present. For keywords taking values, the word points at the result,
  87. somewhere further along in the result vector.
  88.  
  89. Arguments with no /E or /G qualifiers are simply null-terminated strings.
  90. /E argument values are a type byte:
  91.   0 means integer, in which case the next 4 bytes are the value (LSB first)
  92.   non-0 means string: the next 2 bytes are the length, then <length> bytes
  93.                       of string
  94.  
  95. /G arguments are 2 bytes of length, <length> bytes of result.
  96.  
  97.  
  98. Examples:
  99.  
  100. Key definition:  file/a,tabexpand/s
  101. can be matched by
  102.                  -file fred -tabexpand
  103.                  -tf fred
  104.                  -t fred
  105.  
  106.     definition   number=times/e,file/k/a
  107. can be matched by
  108.                  -n 10 -file jim
  109.                  -times 1+7 -file jim
  110.                  -file thingy
  111. but not by
  112.                  thingy -number 14
  113.                  -number 20 -times 4 -file jim
  114.  
  115.  
  116.  
  117. SWI OS_ReadRAMFsLimits (&4A)
  118. ============================
  119.  
  120. Returns R0 start, R1 end (i.e. 1st byte out of area)
  121.  
  122. SWI OS_DelinkApplication/SWI OS_RelinkApplication (&4D/&4E)
  123. ===========================================================
  124.  
  125. These SWIs are used by the Switcher to "disconnect" the application, before
  126. it is switched out. They deal with any entries on vectors where the code
  127. address lies in application space.
  128.  
  129. Delink_Application SWI:
  130.    R0 pointer to buffer
  131.    R1 buffer size
  132.  Returns R1 bytes left in buffer
  133.  The buffer contains records of (vector number, address, R12 value), terminated
  134.  by -1
  135.  
  136. Relink_Application:
  137.   R0 pointer to buffer as set up by Delink
  138.  
  139. SWI OS_HeapSort (&4F)
  140. =====================
  141.  
  142. There is a routine in Arthur2 to sort objects using the HeapSort algorithm
  143. described in Knuth (Sorting and Searching pp.145-149). This is an algorithm 
  144. of average order 23.08N ln N (for n -> infinity), and is worst case N^2. It
  145. is actually guaranteed to be of order N log N. (see the book for more detail)
  146. It's not as fast as QuickSort for 'average' QuickSorts, but doesn't use any
  147. more memory than that initially passed in.
  148.  
  149. ; In    r0 = n (number of elements to sort)
  150. ;       r1 = array(n) of word size objects (r2 determines type)
  151. ;              bit 31 set -> use r4,r5 on postpass
  152. ;              bit 30 set -> build (r1) from r4,r5 in prepass
  153. ;              bit 29 set -> use r6 as temp slot
  154. ;       r2 = address of comparison procedure
  155. ;              Special cases:
  156. ;                0 -> treat r(n) as array of cardinal
  157. ;                1 -> treat r(n) as array of integer
  158. ;                2 -> treat r(n) as array of cardinal*
  159. ;                3 -> treat r(n) as array of integer*
  160. ;                4 -> treat r(n) as array of char* (case insensitive)
  161. ;                5 -> treat r(n) as array of char* (case sensitive)
  162. ;       r3 = wsptr for comparison procedure (only needed if r2 > 5)
  163. ;       r4 = array(n) of things (only needed if r1 & 0xC0000000)
  164. ;       r5 = sizeof(element)    ( ---------  ditto  ---------- )
  165. ;       r6 = address of temp slot (only needed if r5 > 16K or r1 & 0x20000000)
  166.  
  167. ; User sort procedure entered in SVC mode, interrupts enabled
  168. ; r0 = contents of array(1)
  169. ; r1 = contents of array(2)
  170. ; r0-r3 may be corrupted
  171. ; r12 = value requested
  172. ;            (alter at your peril; you'll get the same r12 next time)
  173.  
  174. ; User sort procedure returns:
  175. ;       LT: if f(r0)  < f(r1)
  176. ;       GE: if f(r0) => f(r1)
  177. ; (ie. N_bit and V_bit only considered, Z_bit and C_bit irrelevant)
  178.  
  179.  
  180. SWI OS_ExitAndDie (&50)
  181. =======================
  182.  
  183. Action: SWI Exit performed, named module killed.
  184. r0-r2 are parameters for Exit
  185. r3 pointer to module name
  186.  
  187.  
  188. SWI OS_AddCallBack (&54)
  189. ========================
  190.  
  191. Arthur 2 has a "callback vector", which extends and improves the idea
  192. of a callback handler present in Arthur 1.20. The callback handler is the
  193. property of the current application, and can be used by the application to
  194. do anything it feels like (e.g. task switching).
  195.  
  196. However, callback is also very useful for a class of resident utilities,
  197. e.g. a module that will do a *ScreenSave when a key is pressed. This has
  198. a couple of problems if it tries to use the callback handler:
  199.  
  200. 1) the current application may lose callbacks, and therefore stop working.
  201. 2) if the application is in ReadLine, then the callback doesn't happen until
  202.    the readline returns.
  203.  
  204. We therefore have the callback vector, which is a list of people who have asked
  205. to be called as soon as the MOS isn't busy. Code on the vector is much more
  206. restricted than callback handler code; it musn't change into user mode and it
  207. must always call X-SWIs.
  208.  
  209. In: R0 = address to call
  210.     R1 = value of R12 to be called with.
  211.  
  212. The code must preserve all registers, and exit by MOV PC, r14
  213.  
  214. Note that it isn't necessary to do a SWI OS_SetCallBack; adding to the vector
  215. means you want to be called anyway.
  216.  
  217.  
  218. The MOS now does the following:
  219.  
  220. On exit from a SWI or interrupt routine:
  221.     While anybody is on the callback vector:
  222.          remove the vector entry
  223.          call them
  224.  
  225.     If callback has been requested, call the callback handler
  226.  
  227.  
  228. While waiting for a key in OS_ReadC or INKEY
  229.     While anybody is on the callback vector:
  230.          remove the vector entry
  231.          call them
  232.  
  233.  
  234. SWI OS_ReadDefaultHandler (&55)
  235. ===============================
  236.  
  237. This SWI can be used to read the MOS default handlers (i.e. those set
  238. at reset).
  239.  
  240. In: R0 = reason code. The same numbers as SWI OS_ChangeEnvironment are used.
  241.  
  242. Out: R1=address, R2=workspace, R3=buffer. 0 means not relevant.
  243.  
  244. SWI OS_ReadSysInfo   &58
  245. ------------------
  246.  
  247. This takes a handle in r0, returns results depending on the handle.
  248. Currently r0=0 is the only defined one:
  249.  
  250. In: r0 = 0  => Out: r0 = size (in bytes) screen will be after hard reset.
  251.  
  252.  
  253. SWI OS_Confirm       &59
  254. --------------
  255.  
  256.  If pointer visible, change pointer shape and look at mouse keys too.
  257.                      Flushes mouse buffer first.
  258.  Wait until key pressed.
  259.  Returns: (lowercased) character in r0 (if mouse scanned, LH button = 'y',
  260.                                         other buttons = 'n')
  261.  C set for Escape
  262.  EQ set if r0 = 'y'
  263.